/*
 * Copyright 2002-2016 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.servlet.mvc.condition;

import jakarta.servlet.http.HttpServletRequest;

import org.springframework.lang.Nullable;

/**
 * <p>
 *     org.springframework.web.servlet.mvc.condition.RequestCondition 是 Spring MVC 中用于实现请求条件匹配的一个接口。
 *     它允许开发者根据自定义的条件来决定是否应该处理某个 HTTP 请求。
 *     通过实现 RequestCondition 接口，可以创建更加灵活和细粒度的 URL 映射规则，超越了传统的基于路径、方法或参数的简单映射。
 * 1.主要功能
 * 		自定义条件匹配：你可以根据任意逻辑（如用户角色、HTTP 头信息、查询参数等）来决定是否处理请求。
 * 		组合条件：多个 RequestCondition 可以组合在一起使用，形成更复杂的匹配逻辑。
 * 		优先级控制：当有多个条件都匹配时，可以通过设置优先级来确定哪个控制器方法应该被调用。
 *
 * 2.使用场景
 * 		权限控制：根据用户的角色或权限级别来限制访问某些资源。
 * 		版本控制：为 API 实现版本管理，例如根据 Accept 头中的版本号来路由到不同的处理逻辑。
 * 		设备适配：根据 User-Agent 或其他 HTTP 头信息判断客户端设备类型，并相应地选择不同的视图或数据格式。
 * 		流量分流：根据请求来源或其他因素进行流量分割实验（A/B Testing），将不同类型的请求路由到不同的处理器。
 * 3.接口定义
 * 		RequestCondition 接口有一个核心方法
 *
 * </p>
 * Contract for request mapping conditions.
 *
 * <p>Request conditions can be combined via {@link #combine(Object)}, matched to
 * a request via {@link #getMatchingCondition(HttpServletRequest)}, and compared
 * to each other via {@link #compareTo(Object, HttpServletRequest)} to determine
 * which is a closer match for a given request.
 *
 * @author Rossen Stoyanchev
 * @author Arjen Poutsma
 * @since 3.1
 * @param <T> the type of objects that this RequestCondition can be combined
 * with and compared to
 */
public interface RequestCondition<T> {

	/**
	 * Combine this condition with another such as conditions from a
	 * type-level and method-level {@code @RequestMapping} annotation.
	 * <br> 合并两个条件，例如从类型级别和方法级别的 {@code @RequestMapping} 注解中。
	 * @param other the condition to combine with.
	 * @return a request condition instance that is the result of combining
	 * the two condition instances.
	 */
	T combine(T other);

	/**
	 * Check if the condition matches the request returning a potentially new
	 * instance created for the current request. For example a condition with
	 * multiple URL patterns may return a new instance only with those patterns
	 * that match the request.
	 * <br> 检查条件是否与请求匹配，返回可能为当前请求创建的新实例。例如，具有多个 URL 模式的条件可以仅返回那些与请求匹配的模式的新实例。
	 *
	 * <p>For CORS pre-flight requests, conditions should match to the would-be,
	 * actual request (e.g. URL pattern, query parameters, and the HTTP method
	 * from the "Access-Control-Request-Method" header). If a condition cannot
	 * be matched to a pre-flight request it should return an instance with
	 * empty content thus not causing a failure to match.
	 * @return a condition instance in case of a match or {@code null} otherwise.
	 */
	@Nullable
	T getMatchingCondition(HttpServletRequest request);

	/**
	 * Compare this condition to another condition in the context of
	 * a specific request. This method assumes both instances have
	 * been obtained via {@link #getMatchingCondition(HttpServletRequest)}
	 * to ensure they have content relevant to current request only.
	 */
	int compareTo(T other, HttpServletRequest request);

}
